Skip to content

[clang-doc] Update clang-doc tool to enable mustache templates #138066

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 28, 2025

Conversation

ilovepi
Copy link
Contributor

@ilovepi ilovepi commented May 1, 2025

This patch adds a command line option and enables the Mustache template
HTML backend. This allows users to use the new, more flexible templates
over the old and cumbersome HTML output. Split from #133161.

Co-authored-by: Peter Chou [email protected]

@llvmbot
Copy link
Member

llvmbot commented May 1, 2025

@llvm/pr-subscribers-clang-tools-extra

Author: Paul Kirth (ilovepi)

Changes

This patch adds a command line option and enables the Mustache template
HTML backend. This allows users to use the new, more flexible templates
over the old and cumbersome HTML output. Split from #133161.

Co-authored-by: Peter Chou <[email protected]>


Full diff: https://github.com/llvm/llvm-project/pull/138066.diff

2 Files Affected:

  • (modified) clang-tools-extra/clang-doc/tool/CMakeLists.txt (+7)
  • (modified) clang-tools-extra/clang-doc/tool/ClangDocMain.cpp (+72-20)
diff --git a/clang-tools-extra/clang-doc/tool/CMakeLists.txt b/clang-tools-extra/clang-doc/tool/CMakeLists.txt
index 601a0460d76b3..eccbc99a7ecc4 100644
--- a/clang-tools-extra/clang-doc/tool/CMakeLists.txt
+++ b/clang-tools-extra/clang-doc/tool/CMakeLists.txt
@@ -21,6 +21,13 @@ target_link_libraries(clang-doc
 
 set(assets
   index.js
+  mustache-index.js
+  class-template.mustache
+  comments-template.mustache
+  enum-template.mustache      
+  function-template.mustache
+  namespace-template.mustache      
+  clang-doc-mustache.css
   clang-doc-default-stylesheet.css
 )
 
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 8e8f7053a8f87..a9b631f04ec28 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -18,20 +18,13 @@
 //===----------------------------------------------------------------------===//
 
 #include "BitcodeReader.h"
-#include "BitcodeWriter.h"
 #include "ClangDoc.h"
 #include "Generators.h"
 #include "Representation.h"
-#include "clang/AST/AST.h"
-#include "clang/AST/Decl.h"
-#include "clang/ASTMatchers/ASTMatchFinder.h"
 #include "clang/ASTMatchers/ASTMatchersInternal.h"
-#include "clang/Driver/Options.h"
-#include "clang/Frontend/FrontendActions.h"
 #include "clang/Tooling/AllTUsExecution.h"
 #include "clang/Tooling/CommonOptionsParser.h"
 #include "clang/Tooling/Execution.h"
-#include "clang/Tooling/Tooling.h"
 #include "llvm/ADT/APFloat.h"
 #include "llvm/Support/CommandLine.h"
 #include "llvm/Support/Error.h"
@@ -110,11 +103,7 @@ static llvm::cl::opt<std::string> RepositoryCodeLinePrefix(
     llvm::cl::desc("Prefix of line code for repository."),
     llvm::cl::cat(ClangDocCategory));
 
-enum OutputFormatTy {
-  md,
-  yaml,
-  html,
-};
+enum OutputFormatTy { md, yaml, html, mhtml };
 
 static llvm::cl::opt<OutputFormatTy>
     FormatEnum("format", llvm::cl::desc("Format for outputted docs."),
@@ -123,7 +112,9 @@ static llvm::cl::opt<OutputFormatTy>
                                 clEnumValN(OutputFormatTy::md, "md",
                                            "Documentation in MD format."),
                                 clEnumValN(OutputFormatTy::html, "html",
-                                           "Documentation in HTML format.")),
+                                           "Documentation in HTML format."),
+                                clEnumValN(OutputFormatTy::mhtml, "mhtml",
+                                           "Documentation in mHTML format")),
                llvm::cl::init(OutputFormatTy::yaml),
                llvm::cl::cat(ClangDocCategory));
 
@@ -135,6 +126,8 @@ static std::string getFormatString() {
     return "md";
   case OutputFormatTy::html:
     return "html";
+  case OutputFormatTy::mhtml:
+    return "mhtml";
   }
   llvm_unreachable("Unknown OutputFormatTy");
 }
@@ -168,6 +161,14 @@ static llvm::Error getAssetFiles(clang::doc::ClangDocContext &CDCtx) {
   return llvm::Error::success();
 }
 
+static llvm::SmallString<128> appendPathNative(StringRef Path,
+                                               StringRef Asset) {
+  llvm::SmallString<128> Default;
+  llvm::sys::path::native(Path, Default);
+  llvm::sys::path::append(Default, Asset);
+  return Default;
+}
+
 static llvm::Error getDefaultAssetFiles(const char *Argv0,
                                         clang::doc::ClangDocContext &CDCtx) {
   void *MainAddr = (void *)(intptr_t)getExecutablePath;
@@ -178,13 +179,9 @@ static llvm::Error getDefaultAssetFiles(const char *Argv0,
   llvm::SmallString<128> AssetsPath;
   AssetsPath = llvm::sys::path::parent_path(NativeClangDocPath);
   llvm::sys::path::append(AssetsPath, "..", "share", "clang-doc");
-  llvm::SmallString<128> DefaultStylesheet;
-  llvm::sys::path::native(AssetsPath, DefaultStylesheet);
-  llvm::sys::path::append(DefaultStylesheet,
-                          "clang-doc-default-stylesheet.css");
-  llvm::SmallString<128> IndexJS;
-  llvm::sys::path::native(AssetsPath, IndexJS);
-  llvm::sys::path::append(IndexJS, "index.js");
+  llvm::SmallString<128> DefaultStylesheet =
+      appendPathNative(AssetsPath, "clang-doc-default-stylesheet.css");
+  llvm::SmallString<128> IndexJS = appendPathNative(AssetsPath, "index.js");
 
   if (!llvm::sys::fs::is_regular_file(IndexJS))
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
@@ -215,6 +212,54 @@ static llvm::Error getHtmlAssetFiles(const char *Argv0,
   return getDefaultAssetFiles(Argv0, CDCtx);
 }
 
+static llvm::Error getMustacheHtmlFiles(const char *Argv0,
+                                        clang::doc::ClangDocContext &CDCtx) {
+  if (!UserAssetPath.empty() &&
+      !llvm::sys::fs::is_directory(std::string(UserAssetPath)))
+    llvm::outs() << "Asset path supply is not a directory: " << UserAssetPath
+                 << " falling back to default\n";
+  if (llvm::sys::fs::is_directory(std::string(UserAssetPath)))
+    return getAssetFiles(CDCtx);
+
+  void *MainAddr = (void *)(intptr_t)getExecutablePath;
+  std::string ClangDocPath = getExecutablePath(Argv0, MainAddr);
+  llvm::SmallString<128> NativeClangDocPath;
+  llvm::sys::path::native(ClangDocPath, NativeClangDocPath);
+
+  llvm::SmallString<128> AssetsPath;
+  AssetsPath = llvm::sys::path::parent_path(NativeClangDocPath);
+  llvm::sys::path::append(AssetsPath, "..", "share", "clang-doc");
+
+  llvm::SmallString<128> DefaultStylesheet =
+      appendPathNative(AssetsPath, "clang-doc-mustache.css");
+  llvm::SmallString<128> NamespaceTemplate =
+      appendPathNative(AssetsPath, "namespace-template.mustache");
+  llvm::SmallString<128> ClassTemplate =
+      appendPathNative(AssetsPath, "class-template.mustache");
+  llvm::SmallString<128> EnumTemplate =
+      appendPathNative(AssetsPath, "enum-template.mustache");
+  llvm::SmallString<128> FunctionTemplate =
+      appendPathNative(AssetsPath, "function-template.mustache");
+  llvm::SmallString<128> CommentTemplate =
+      appendPathNative(AssetsPath, "comments-template.mustache");
+  llvm::SmallString<128> IndexJS =
+      appendPathNative(AssetsPath, "mustache-index.js");
+
+  CDCtx.JsScripts.insert(CDCtx.JsScripts.begin(), IndexJS.c_str());
+  CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
+                               std::string(DefaultStylesheet));
+  CDCtx.MustacheTemplates.insert(
+      {"namespace-template", NamespaceTemplate.c_str()});
+  CDCtx.MustacheTemplates.insert({"class-template", ClassTemplate.c_str()});
+  CDCtx.MustacheTemplates.insert({"enum-template", EnumTemplate.c_str()});
+  CDCtx.MustacheTemplates.insert(
+      {"function-template", FunctionTemplate.c_str()});
+  CDCtx.MustacheTemplates.insert(
+      {"comments-template", CommentTemplate.c_str()});
+
+  return llvm::Error::success();
+}
+
 /// Make the output of clang-doc deterministic by sorting the children of
 /// namespaces and records.
 static void
@@ -290,6 +335,13 @@ Example usage for a project using a compile commands database:
     }
   }
 
+  if (Format == "mhtml") {
+    if (auto Err = getMustacheHtmlFiles(argv[0], CDCtx)) {
+      llvm::errs() << toString(std::move(Err)) << "\n";
+      return 1;
+    }
+  }
+
   // Mapping phase
   llvm::outs() << "Mapping decls...\n";
   auto Err =

Copy link
Contributor Author

ilovepi commented May 1, 2025

I'm wondering if this should be earlier in the stack to facilitate better testing.

@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from e04a368 to f70cfdf Compare May 6, 2025 21:33
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch 2 times, most recently from 3e6a31d to 864ff1a Compare May 6, 2025 22:51
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from f70cfdf to d18b211 Compare May 6, 2025 22:51
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from 864ff1a to f67bcd6 Compare May 7, 2025 01:59
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from d18b211 to 622f2ef Compare May 7, 2025 01:59
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from f67bcd6 to cf590a7 Compare May 7, 2025 02:54
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch 2 times, most recently from c7955f5 to b5a3bc4 Compare May 7, 2025 03:23
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch 2 times, most recently from 4050366 to de4ff28 Compare May 7, 2025 03:25
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from b5a3bc4 to 3107a2f Compare May 7, 2025 03:25
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from d829981 to ec5d920 Compare May 17, 2025 05:42
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from 26fd7a5 to 428fae4 Compare May 20, 2025 18:26
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from ec5d920 to 049c4ae Compare May 20, 2025 18:26
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from 428fae4 to 6d69f64 Compare May 20, 2025 21:05
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch 2 times, most recently from 5475c90 to e94b231 Compare May 22, 2025 21:18
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch 2 times, most recently from 2d48537 to f15e49b Compare May 22, 2025 21:22
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from e94b231 to 47a8fc0 Compare May 22, 2025 21:23
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from f15e49b to 7deaf5a Compare May 23, 2025 21:58
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from 47a8fc0 to 5dd55e8 Compare May 23, 2025 21:58
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from 7deaf5a to 515b014 Compare May 23, 2025 23:01
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from 5dd55e8 to 3ddddd4 Compare May 23, 2025 23:01
@ilovepi ilovepi requested a review from petrhosek May 24, 2025 04:10
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from 515b014 to 3ac33bf Compare May 27, 2025 22:22
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from 3ddddd4 to fb5adf7 Compare May 27, 2025 22:22
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from 3ac33bf to 2f04040 Compare May 27, 2025 22:46
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from fb5adf7 to bfd1d03 Compare May 27, 2025 22:46
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from 2f04040 to f242226 Compare May 27, 2025 22:49
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from bfd1d03 to dc1b8f6 Compare May 27, 2025 22:49
Copy link
Contributor Author

ilovepi commented May 28, 2025

Merge activity

  • May 28, 5:18 AM UTC: A user started a stack merge that includes this pull request via Graphite.
  • May 28, 5:23 AM UTC: Graphite rebased this pull request as part of a merge.
  • May 28, 5:25 AM UTC: @ilovepi merged this pull request with Graphite.

@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-serializer branch from f242226 to cdb996a Compare May 28, 2025 05:20
Base automatically changed from users/ilovepi/clang-doc-mustache-serializer to main May 28, 2025 05:22
This patch adds a command line option and enables the Mustache template
HTML backend. This allows users to use the new, more flexible templates
over the old and cumbersome HTML output. Split from #133161.

Co-authored-by: Peter Chou <[email protected]>
@ilovepi ilovepi force-pushed the users/ilovepi/clang-doc-mustache-clang-doc-tool branch from dc1b8f6 to d8ddebc Compare May 28, 2025 05:23
@ilovepi ilovepi merged commit 79023db into main May 28, 2025
6 of 10 checks passed
@ilovepi ilovepi deleted the users/ilovepi/clang-doc-mustache-clang-doc-tool branch May 28, 2025 05:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants